home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Libris Britannia 4
/
science library(b).zip
/
science library(b)
/
PROGRAMM
/
COBOL
/
H309.ZIP
/
COBXREF.ZIP
/
COBXRF.EXE
/
COBXREF.DOC
< prev
next >
Wrap
Text File
|
1993-06-16
|
13KB
|
464 lines
----------------------------------------------------------------------------
COBXREF
VERSION 1.11
USER GUIDE
Copyright (c) TRANTOR LTD, 1993
----------------------------------------------------------------------------
CONTENTS
Chapter 1. Introduction
Chapter 2. Description
Chapter 3. Restrictions
Chapter 4. Running the Program
Chapter 5. The Future
Chapter 6. Registration
Appendix A. Reformatting Table definition
Appendix B. Latest changes
==============================================================================
TRANTOR LTD Home/Office 0639-633072
GREEN HEDGES BUNGALOW International 44-639-633072
PONTARDAWE ROAD Mobile 0836-795445
BRYNCOCH Fax (manual switch, on request)
NEATH SA10 7YL Compuserve 100040,471
WEST GLAMORGAN Directors:
SOUTH WALES N.H.Jennings, B.Sc., CEng, MBCS, FIAP
UK D.P.Jennings
==============================================================================
----------------------------------------------------------------------------
CHAPTER ONE
----------------------------------------------------------------------------
INTRODUCTION
This program is a utility which is intended to assist in analysing and
documenting COBOL source.
It is NOT a toy or a demo, but a fully working program which is intended
for daily use by the professional COBOL programmer. It can be used on a PC
to cross reference COBOL code from ANY machine.
Command-line parameters are provided, so that COBXREF can be used within a
BAT file.
----------------------------------------------------------------------------
CHAPTER TWO
-----------------------------------------------------------------------------
Description
===========
This is a simple cross reference program for COBOL source. Since it is not
part of a COBOL compiler, it does not perform a full parse and syntax
analysis of the source. It can recognize certain types of COBOL item,
including comments, literals, paragraph names, punctuation, verbs and
reserved words,
It is, however, very simple-minded, and will report anything which it does
not understand. This should not be a problem to most users, except that
prints may be larger than necessary.
COBOL verbs and Reserved words are only recognised because they are found
in a table. You can edit this table to include or exclude other items.
There is a limit of 600 lines in the table.
Paragraph and Data names are recognised by various checks, not from the
table.
COBOL comments are not included in the cross reference.
References
==========
All references are to the input record number, NOT the sequence number. Due
to the asynchronous nature of the internal processing, the reported line
number may sometimes be out by 1.
Format
======
You can choose either a 79-column or 132-column format by the XREF
parameter.
You can also choose to view the cross reference on the screen, as well as
creating a report.
----------------------------------------------------------------------------
CHAPTER THREE
----------------------------------------------------------------------------
Known restrictions
==================
Big Red Switch
--------------
COBXREF can occasionally cause the machine to hang - exact
circumstances are not known, but it is believed to be caused by a bug in
the COBOL compiler which results in working storage becoming corrupted.
It will also hang if the input file contains only comment lines, ie no
COBOL text.
Size of source
--------------
This version will allow source programs of up to about 9000 lines,
depending on the number of items (maximum 3000) and the number of
references to those items (maximum 12000). With these restrictions, the EXE
file size is almost 500kb.
If either table overflows, the fact will be displayed, but processing will
continue. The line number at which overflow occurs will also be reported.
The cross reference produced will be incomplete, but may still be of use.
The counts at the end of the run will show by how much the table overflowed.
Case
----
COBXREF will currently report upper and lower case versions of the same
word separately, even though the COBOL compiler should treat them as
identical.
Print Formatting
----------------
Currently, no print formatting (headings, page throws, page numbers) is
included in the output file - it is a plain ASCII text file.
Miscellaneous quirks
--------------------
COBXREF currently includes COBOL PICTURE clauses such as X(132). I will fix
this later.
Numeric literals are also included, although non-numeric literals may
optionally be suppressed.
Non-numeric literals will be truncated to 30 characters, including the
initial quote or apostrophe. This may lead to references to two or more
similar literals being combined.
Some COBOL operators and punctuation, such as - and * (in COMPUTE
statements) will be included. I will also fix this later.
----------------------------------------------------------------------------
CHAPTER FOUR
----------------------------------------------------------------------------
Running the program
===================
Run the program by typing COBXREF, followed by any required command-line
parameters, at the MS-DOS prompt. The Input filee is the most commonly used
parameters:
COBXREF IN=REMTEST.STR
If you do not enter an input filename, you will be asked for it.
Provided that the input file is specified, the REGISTERED version is
suitable for inclusion in a batch (.BAT) file, and will not ask for input
from the keyboard.
Parameters
----------
The following command line parameters are available. If the parameters are
given in the order shown, the keywords for the first three are optional,
but they should be used for compatibility with future releases.
Note that the keywords shown (ie before the equals sign) may be in upper or
lower case.
Main Parameters
===============
IN= Input filename. The default extension, CBL, will be added if not
supplied
XREF= Type of cross reference required. Up to two characters.
First character - cross reference type
The following types are available
1 (Default) Verbs, reserved words and most literals are
excluded
2 Currently the same as 1.
3 Includes only Datanames, Paragraph and Section
names.
9 All items, including verbs, reserved words and
literals are included
Second Character - Print/display format
V or v Narrow format list (79 cols) and also display on
screen
S or s Narrow format list
Space Wide format list, 132 columns
Example: XREF=2S
TAB= Reformatting table name. Default extension is TBL
CIN= Input source format.
This parameter is in two parts
Part 1 (1 digit)
Number of columns reserved for sequence numbers on input
source. Default is 6, valid numbers are 0 to 6
Part 2 (optional - 3 digits)
Size of COBOL text area from Margin-B to Margin-R. For
standard 80-column COBOL, this will be 061, as Margin-B is
12 and Margin-R is 72.
Maximum value is 132, default is 061.
PRINT=filename
The print file to which the cross reference is written.
DIAG=n Diagnostic parameter
This invokes diagnostic displays if set to certain values.
It should not normally be used, as it is mainly for our use in
diagnosing bugs. If used, it is recommended that SYSOUT is directed to a
file, as follows
COBXREF INFILE DIAG=3 > TRACE
You may then have to hit return a few times, because you cannot see the
console prompts - they are diverted to the file!
EXAMPLE:
COBXREF IN=PROGRAM TAB=COBTABLE.TXT CIN=4061
Further parameters
===================
These do not have any useful effect, they are simply retained because the
program was created from COBFORM. As is often the case in this kind of
development, it was easier to leave them in than take them out.
LEV= Indentation (default 3)
MDIR= MACRO directory
PATH= Insert Trace and Path Analysis code
FST= Same line after full stop or comma if N (default Y)
INC=ABC Record selection
SECT= Display section names
COUT=
STR=
USAGE=
----------------------------------------------------------------------------
CHAPTER FIVE
----------------------------------------------------------------------------
The Future
==========
Plans for further enhancements include the following:
Recognition of Paragraph and Datanames
A minimum XREF which includes only Paragraph and Datanames
Recognition and optional exclusion of Picture clauses
----------------------------------------------------------------------------
CHAPTER SIX
----------------------------------------------------------------------------
Registration
=============
In common with most Shareware, registration on the following terms is
allowed for personal use only. All rights are retained, and Corporate
users, and those using this software in the course of a business, are
expected (and legally obliged) to purchase a commercial licence, which is
reasonably priced.
This software has taken many years to develop, and I would like to see some
return on the investment in effort, before COBOL is finally buried!
Please send 12 Pounds Sterling for the registered version of any of our PC
programs, to the address given at the start of this file. This includes VAT
and post & packing, and a VAT receipt can be supplied on request. (UK only)
In return for registration, I will supply some or all of the following,
depending on the particular product:
The latest version, without the advertising screens
Compuserve support
Telephone support (UK office hours only please)
Special enhancements on request
Prices correct as at 1st of June 1993, but we reserve the right to change
them without notice.
(Note that after paying for post, packing and media, phone and COMPUSERVE
costs, VAT and personal taxes, I end up with less than 6 pounds per sale
for my efforts. I don't think that is unreasonable.)
For non-UK users:
Please send $25 or equivalent. This is because
a) Overseas mailing costs more
b) the bank charges a minimum of $4 for currency conversion (cash) or $9
for cashing a foreign cheque (check).
Where possible, I would prefer the cash, because I can batch it up and
pay only one conversion charge for several registrations. (Always the
optimist!)
Overseas cheques should be made payable to N. Jennings, NOT TRANTOR
----------------------------------------------------------------------------
APPENDIX A
----------------------------------------------------------------------------
Reformatting table definition
-----------------------------
Table contents
--------------
Column 1
COBOL Division code, I, E, D, P or space. An item will only match if it
occurs in the specified division. If space, it will match in any division.
Columns 2-31
The item, a COBOL word, paragraph or dataname
Column 32
Item type,
V=verb
J=structure verb (COBFORM only)
L=level number
R=Reserved word
Other values are documentary only
Columns 33-34
Default alignment, 2 digits or spaces if no special alignment is required
(COBFORM only)
Columns 35-36
Length of textual replacement, or spaces if no replacement is required. It
is only necessary to specify a length if the textual replacement contains
embedded spaces. (Not used by COBXREF)
Columns 37-66
Textual replacement, if any. (Not used by COBXREF)
----------------------------------------------------------------------------
APPENDIX B.
----------------------------------------------------------------------------
Latest changes
==============
Version 1.11
============
This is the first version released for general use. Previous versions were
for test only.